Port PeachPDF's CSS Fragmentation engine for real page-break support - #263

Fragment/LineFragment/TextFragment/BoxFragment/FragmentainerFragment/
FragmentTree, plus SliceGeometry for box-decoration-break, ported from
PeachPDF's fragment-tree design (Fragments/Fragment.cs) into this
project's string-CSS/CssBox model. This is the output shape only - no
producer yet, and nothing references these types. MarginBoxFragment/
FootnoteAreaFragment (@page margin boxes, float: footnote) are
dropped, out of scope for this port.

Also adds PageBandGeometry, a minimal per-fragmentainer band/margin
value computed from the container's single fixed page size, standing
in for PeachPDF's variable-geometry PageGeometryTable (not needed
since this port doesn't build per-page @page overrides).

PageBand, BreakValues, MonolithicContent, BreakToken/BlockBreakToken/
InlineBreakToken, and BreakRelaxation, ported from PeachPDF's
Fragmentation/ module and reduced to this port's scope: no flex/grid/
multi-column (no FlexBreakToken/GridBreakToken/nested fragmentainers),
no directional break-before/after (no @page :left/:right matching),
and HTML-Renderer's own smaller replaced-element/vertical-writing-mode
surface. TableBreakToken is deferred to the table-fragmentation stage,
where it can be shaped against HTML-Renderer's own row/cell model
instead of guessed at now.

InlineBreakToken carries PeachPDF's documented custom Equals/
GetHashCode (content-based, not the compiler's reference-equality
default for its ResumePath list) - a measured footgun there that
silently breaks the pass-count "no progress" backstop otherwise.

Still no producer - nothing outside this new code references it yet.

HtmlContainerInt.PerformLayout now builds a FragmentTree from the
finished box tree via a first-cut FragmentEmitter: one
FragmentainerFragment spanning the whole document, no break tokens
produced yet. This proves the layout -> fragment tree plumbing works
before any real multi-page resumption exists, and is the stepping
stone the paint stage builds on next (painting from the fragment tree
instead of the live box tree).

Every BoxFragment/LineFragment/TextFragment gets built unconditionally
for the whole box tree, including display:none/hidden content -
display/visibility is left as a paint-time concern, matching the
fragment tree's role as a structural fact rather than a rendering
decision.

No behavior change: nothing reads FragmentTree yet, and the full
image-diff regression suite (30/30) and PDF generator tests (2/2)
are unaffected.

FragmentPainter walks a FragmentainerFragment and paints it, mirroring
CssBox.Paint/PaintImp's display/visibility gating, fixed-position clip
suspension, visibility culling, and z-order child recursion exactly -
but reading geometry from BoxFragment/LineFragment/TextFragment
instead of the live, mutable box tree.

Rather than duplicating background/border/text/decoration painting,
CssBox.PaintBackground/PaintWords/PaintDecoration are widened from
protected/private to internal and called directly from the fragment
painter, so this is a faithful re-shaping of the existing, tested
paint code rather than a parallel reimplementation with its own risk
of drift. CssBoxImage/CssBoxHr/CssBoxFrame (replaced/rule leaf types)
still delegate wholesale to their own existing Paint() for now - they
are monolithic, so their one fragment always covers their whole box,
and real per-type content painters are follow-on work once actual
multi-fragment splitting exists for them to matter. A new internal
CssBox.ListItemBox accessor exposes the synthetic marker box (never
part of Boxes) so it paints in its usual place.

HtmlContainerInt gains an internal PerformPaint(RGraphics, Fragment-
ainerFragment) overload alongside the existing PerformPaint(RGraphics)
- not yet the default path (that cutover is later, once the full
fragmentation+paint port is done), so both coexist deliberately.

Verified two ways: a pixel-for-pixel self-consistency check across
five representative samples (text, tables, backgrounds/borders/hr,
fixed position, list markers), and - by temporarily redirecting
HtmlContainer.PerformPaint through the new path and reverting after -
the entire existing 30-sample image-diff regression suite, all
pixel-identical to today's output.

Real multi-page fragmentation for block content, without the break-
token/pass-loop machinery from Stage C: PeachPDF's model has the
parent frame position each child (so it can consult fragmentation
state before laying it out); HTML-Renderer's has each child position
itself via MarginTopCollapse(prevSibling). Rather than restructure
positioning responsibility to match PeachPDF, this keeps HTML-
Renderer's existing single top-down positioning pass (every box gets
a final absolute Y in one walk, as today) and adds four *local*
corrections that only need a box's own natural position or already-
finished height - none of them need multi-pass resumption:

- Forced break-before/break-after: page (and the legacy always
  value, since this engine's CSS parser accepts it on the modern
  properties directly rather than normalizing it away) pushes a
  box's start to the next page's content top.
- CSS Fragmentation 5.2 margin truncation: a collapsed margin that
  alone crosses a page boundary is discarded, and content starts
  flush at the next page instead of paginating through blank space.
- break-inside: avoid (and monolithic content) relocates a box's
  whole subtree to the next page when it straddles a boundary and
  fits on one page, via CssBox.OffsetTop (already existed, used by
  table cell vertical-align).
- Keep-with-next walks backward through preceding siblings chained
  by break-after/break-before: avoid and moves them along with a
  relocated box, so a heading is never left stranded.

BlockBreakToken/FragmentainerContext stay unused for now - they're
for problems this stage doesn't have (can't-restart-from-scratch
inline re-entry, table row continuation), reserved for D3/D4 where
they're actually needed.

Also ports the fragmentation-relevant half of PeachPDF's UA default
stylesheet: h1-h6 { break-after: avoid } and thead/tfoot { break-
inside: avoid }, replacing this engine's own older, more aggressive
`h1 { page-break-before: always }` default - harmless while break-
before was unconsumed, but forces a spurious leading blank page now
that layout actually reads it.

Two real bugs surfaced and fixed via the existing regression suite
while building this: CssBox.OffsetTop's amount, if also applied to
ActualBottom directly, double-counts the shift because ActualBottom
is a computed property (Location.Y + Size.Height) that already moves
with Location.Y - caught by the Tables baseline. And a forced break-
before must be suppressed when a box has no previous sibling (css-
break-3 3.1: the break point before a container's first child *is*
the break point before the container, which for a box with no
ancestor to propagate to is simply inert) - caught by a page-count
regression on a one-page document opening with an <h1>.

New Source/Test/HtmlRenderer.PdfSharp.Test/StageD2VerificationTest.cs
covers forced break-before (modern and legacy syntax), break-inside:
avoid, keep-with-next, multi-page paragraph flow, and margin
truncation. Full existing suite (30 image-diff baselines + PDF
generator tests) unaffected - WinForms/WPF's unbounded PageSize
sentinel means HasRealPageGrid is false there, so none of this new
logic activates outside real pagination.

FragmentEmitter previously (D1) always produced exactly one
FragmentainerFragment spanning the whole document - correct only
because nothing had real multi-page positions yet. Now that D2 gives
every box a correct absolute position across however many pages it
spans, the emitter walks the finished box tree once per page band
(HtmlContainerInt.PageIndexOf/PageTopOf/PageBottomOf, added for this)
and builds one BoxFragment per box per page it has content on,
splitting a box that spans a page boundary into multiple fragments
with fragmentainer-local coordinates - matching what the fragment
tree is supposed to mean.

A page-slot nothing has content in is never materialized (CSS Paged
Media 3 3.2's blank-page skipping falls out of the walk rather than
being special-cased), which is also why the huge-margin case from the
D2 commit doesn't produce a run of empty fragmentainers.

Containers without a real page grid (WinForms/WPF's unbounded
PageSize sentinel) keep the single-fragmentainer path from D1
unchanged.

IsFirstFragment/IsLastFragment are derived from which page slot a
box's own top/bottom fall in; box-decoration-break slicing
(distinguishing a genuine break edge from a real box edge for
border/background painting) stays a no-op for now - deferred to
Stage E2, once paint actually needs to draw a spanning box correctly.

New Source/Test/HtmlRenderer.IntegrationTest/StageD2FragmentBucketing
SmokeTest.cs verifies multiple fragmentainers with ascending, gapless
slot indices for a dense multi-page document, and that a huge margin
doesn't produce a run of blank fragmentainers. Full existing suite
(32 image-diff baselines + 9 PDF/PdfSharp tests) unaffected.

Extends the D2 pattern (local corrections to an already-computed
layout, not resumable re-entry) to inline content. CreateLineBoxes
already computes every line's final position in one pass; nothing
about deciding where a paragraph should break needs to re-measure
words or re-run hyphenation, so - unlike PeachPDF, where inline
resumption genuinely can't restart from scratch - InlineBreakToken's
pass-loop machinery isn't needed here either, the same way
BlockBreakToken turned out not to be for D2.

InlineFragmentation.ApplyLineBreaking runs right after CreateLineBoxes
for a block containing only inline content: walks its LineBoxes in
document order, and where a line would straddle a page boundary
(css-break-3 4.1: a line box is monolithic, the whole line moves, not
just the words that don't fit), shifts it - and everything after it -
down to the next page's content top via a new CssLineBox.ShiftLine,
honoring orphans (push the break earlier if too few lines would
remain before it) and widows (pull more lines across if too few would
remain after). This replaces the old per-word CssRect.BreakPage nudge
for paginated content; that method (and CssBox.BreakPage) are now
dead for real pagination but left in place until Stage F3's planned
cleanup, once the old paint path is fully retired.

New Source/HtmlRenderer/Core/Dom/CssLineBox.cs members: LineTop
(mirrors the existing LineBottom) and ShiftLine (moves every word and
per-box rectangle on the line, reusing the existing OffsetRectangle
helper).

Caught and fixed one MSTest parallelism issue while adding coverage:
this assembly parallelizes at the method level, and HtmlContainerInt's
adapter singletons aren't safe against two full layout passes running
concurrently - StageD2FragmentBucketingSmokeTest needed the same
[DoNotParallelize] HtmlRenderingRegressionTests already carries, or it
intermittently reported an empty fragment tree despite correct
underlying geometry (confirmed by direct inspection in isolation).

New tests: StageD3VerificationTest.cs (PdfSharp page-count checks for
long-paragraph pagination, widows, orphans) and StageD3PrecisionTest.cs
(direct line-position inspection - no line ever straddles a page
boundary across 60+ lines, and a widows:3 paragraph never leaves fewer
than 3 lines alone at the top of a page). Full existing suite (34
image-diff/fragment tests + 12 PDF/PdfSharp tests) green.

Two independent corrections, both gated on a real page grid:

- Row-level break-inside: avoid (or the legacy page-break-inside) on
  the table itself: replaces the old crude per-cell CssRect.BreakPage
  retry loop (which re-ran the whole row from scratch via a decrement-
  and-continue) with the same local shift-the-whole-row-down approach
  D2 uses for blocks, built on the real page-grid math instead of
  BreakPage's modulo arithmetic. Rows aren't avoided from splitting by
  default - css-tables-3 6.1 permits a row to fragment (each cell
  independently), which already happens correctly with no correction
  at all, since a cell's own content already flows across the
  boundary via BlockFragmentation/InlineFragmentation.

- Repeated <thead> (css-tables-3 6.2), gated on the header carrying an
  avoiding break-inside (the UA default stylesheet sets this - see
  the earlier "bring in PeachPDF's fragmentation UA defaults" commit).
  Unlike everything in D2/D3, this genuinely needs layout-time space
  reservation, not just a local position shift: painting a repeated
  header on top of a body row that already flows into that space
  would overlap it. CssLayoutEngineTable's row loop now reserves
  headerHeight at the top of every continuation page before
  positioning that page's first row, and builds a detached clone of
  the header's rows there via the new TableHeaderRepeat helper -
  real cloned CssBox instances (not a fragment-tree-only proxy, so
  the repeat is visible through both the existing scroll-offset PDF
  pipeline and the new fragment tree without teaching two rendering
  paths about "one source, several positions"). Clones are stored on
  a new CssBox.RepeatedHeaderRows list - not part of Boxes, so
  re-running table layout can never mistake them for real content -
  and painted/emitted the same way CssBox.ListItemBox already is, in
  both CssBox.PaintImp and FragmentEmitter.

Found and fixed one real positioning bug while wiring this up: a
<tr> box's own Location is never assigned by the row loop (only its
cells' is), so using the source header row's Location as a clone's
positioning reference silently offset every repeat by however far
that stale value happened to be from the row's true rendered top -
fixed by referencing the row's first cell instead, caught by a
precision test asserting the repeat lands exactly at its page's
content top, not off by that stale offset.

New tests: StageD4RepeatedHeaderTest.cs (precise inspection - text
content matches, position is exactly flush at each continuation
page's top, never repeated onto the table's own first page) and
StageD4VerificationTest.cs (PdfSharp: a 60-row table with a header
spans multiple real PDF pages without error). Full existing suite (35
image-diff/fragment tests + 13 PDF/PdfSharp tests) unaffected.

Replaces the old measure-once-then-scroll-offset-loop pagination
(while (scrollOffset > -container.ActualSize.Height) { AddPage();
scrollOffset -= pageSize.Height; PerformPaint(g); }) with
foreach (var fragmentainer in container.FragmentTree.Fragmentainers).
The fragment tree is now what actually drives real PDF output, not
just an internal structure nothing consumed yet - the first point in
this port where that's true.

Blank-page skipping (CSS Paged Media 3 3.2) falls out for free: a
content-empty page slot is never materialized as a fragmentainer (see
FragmentEmitter), so it's simply absent from this loop instead of
needing to be detected and special-cased.

HandleLinks no longer maps a link's document-Y to a page via a bare
pageSize.Height multiply/divide - slot indices aren't contiguous once
blank-page skipping is live. It now builds a slot-to-page-index map
from the materialized fragmentainers and tests each link's rectangle
against each fragmentainer's own Geometry band.

HtmlRenderer.PdfSharp gains InternalsVisibleTo access to the core
assembly (matching the existing WinForms/WPF grant) so it can reach
HtmlContainerInt.FragmentTree and the new PerformPaint(RGraphics,
FragmentainerFragment) overload - both stay internal rather than
becoming public API while this port is still underway.

Found and fixed a real bug in FragmentEmitter while wiring this up:
Finish() computed the last page slot from container.ActualSize.Height
as if it were an absolute document-Y coordinate, but ActualSize.Height
is document height *excluding* the root box's own top offset
(ActualSize.Height = ActualBottom - Root.Location.Y) - using it
directly double-subtracted MarginTop inside PageIndexOf and silently
under-reported the fragment tree's page count whenever content's true
bottom landed just past a boundary ActualSize.Height alone hadn't yet
crossed. This had been latent since D1/D2 (FragmentTree was structurally
present but never checked against real PDF page counts) and was only
caught here because F1 is the first place the fragment tree's own page
count actually has to be correct, not just non-empty.

New StageF1VerificationTest.cs: web/anchor links across pages don't
throw and produce link annotations, and a huge-margin document
produces no run of blank pages through the real pipeline. Full
existing suite (35 image-diff/fragment tests + 15 PDF/PdfSharp tests,
up from 13 now that the new pipeline exercises every prior stage's
page-count assertions for real) green.

HtmlContainerInt.PerformPaint(RGraphics g) - the overload every
WinForms/WPF control (HtmlPanel, HtmlLabel, HtmlToolTip, HtmlControl,
HtmlRender's image/metafile renderers) ultimately calls - now paints
through FragmentPainter whenever the fragment tree has exactly one
fragmentainer, which is every case that reaches this overload today:
WinForms/WPF's continuous single-surface rendering has no real page
grid, so FragmentEmitter.Finish always gives it one fragmentainer
spanning the whole document (its no-real-page-grid path, built back
in D1). A caller with a real multi-page grid that somehow reaches this
overload instead of the fragmentainer-aware one PdfGenerator always
uses falls back to the old CssBox.Paint walk, unchanged - not a case
that exists in this codebase today, but a safe fallback rather than
silently truncating to one page's content if it ever did.

No new verification needed beyond what already exists: this is the
same swap Stage E1 already proved pixel-identical via a temporary
redirect (reverted after that stage's commit) across the entire
regression suite, now made permanent. The full existing suite (35
image-diff/fragment tests + 15 PDF/PdfSharp tests) stays green with
zero baseline changes, run directly against this as the real default
path for the first time - not a temporary redirect.

FragmentPainter is now the only paint implementation reached by any
of the three platform projects (WinForms/WPF via this overload,
PdfSharp via the fragmentainer-aware one from F1) for ordinary
content. CssBox.Paint/PaintImp remain as the one documented fallback
and are not yet retired - that's F3, once this has had time to prove
itself.

CssBox.BreakPage and CssRect.BreakPage - the old modulo-arithmetic
"does this straddle a page, nudge it down" mechanism - are now fully
superseded: BlockFragmentation (D2), InlineFragmentation (D3), and
CssLayoutEngineTable's row-avoidance correction (D4) all replace their
call sites with page-grid-aware corrections. CssRect.BreakPage had
exactly one remaining caller (CssLayoutEngine.FlowBox's per-word
nudge, dead since D3 - a line box is monolithic, so lines move as a
whole via InlineFragmentation.ApplyLineBreaking, not word by word);
CssBox.BreakPage had none. Both deleted along with that call site.

This is a *narrower* cleanup than the plan's original F3 scope
("delete CssBox.Paint/PaintImp"), by design: FragmentPainter turns
out to still genuinely depend on CssBox.Paint/PaintImp, not just as a
temporary fallback - it delegates to them for CssBoxImage/CssBoxHr/
CssBoxFrame's own PaintImp overrides (E1's deliberate scope
reduction: real per-type content painters are follow-on work), and
the base PaintImp is what actually paints CssBox.ListItemBox and
CssBox.RepeatedHeaderRows (D4), neither of which override it. Deleting
CssBox.Paint/PaintImp now would break list markers and repeated table
headers, not just remove dead code - confirmed by grep before touching
anything: FragmentPainter.cs has three live call sites into it, plus
CssBox.PaintImp's own body still calls it for RepeatedHeaderRows.

Full existing suite (35 image-diff/fragment tests + 15 PDF/PdfSharp
tests) green - this change touches every paginated document's inline
flow, verified rather than assumed safe.

Ports PeachPDF's IFragmentContentPainter/FragmentContentPainters
architecture: a stateless painter per replaced/leaf box type, dispatched
by FragmentPainter instead of delegating into CssBox.Paint. The actual
per-pixel drawing logic stays on the CssBox subclasses (extracted from
their PaintImp bodies into internal methods PaintImp itself now also
calls, so there is exactly one implementation, not a parallel one) -
this keeps the port a faithful re-shaping rather than a rewrite.

CssBoxImage/CssBoxFrame gained an explicit EnsureImageLoadStarted/
EnsureVideoImageLoadStarted method: their lazy image-load trigger lives
in PaintImp today and is the *primary* load trigger for the common
async case (MeasureWordsSize only starts loading when
AvoidAsyncImagesLoading/AvoidImagesLateLoading is set), so the new
painters must replicate it or async images would never load.

List item markers previously painted via a direct box.ListItemBox.Paint(g)
call reading the live mutable tree; FragmentEmitter now builds a real
BoxFragment for the marker (BoxFragment.MarkerFragment, kept separate
from Children to preserve CssBox.PaintImp's paint-after-clip-pop timing,
since an outside-position marker can legitimately hang outside the
element's own overflow clip) and FragmentPainter paints it from there.

CssBox.Paint/PaintImp are NOT deleted: HtmlRenderer.PdfSharp.HtmlContainer
still exposes a public single-surface PerformPaint(XGraphics) overload
that a caller can reach directly (bypassing PdfGenerator's per-fragmentainer
loop) with a real multi-fragmentainer FragmentTree, which the fallback
`_root.Paint(g)` branch in HtmlContainerInt.PerformPaint(RGraphics) still
serves correctly. Deleting it would require new page-stacking transform
logic this session doesn't have a tested replacement for - left as a
real, live-verified deviation from the original plan's F3 assumption.

Full regression suite (35 image-diff tests) and PDF test suite (15 tests)
pass unchanged; all TFMs build clean across the whole solution.

Found while giving FragmentPainter a page-origin translate so
HtmlContainerInt.PerformPaint(RGraphics)'s multi-fragmentainer fallback
could stop depending on CssBox.Paint: FragmentPainter.PaintFragmentContent
painted line backgrounds/borders from the fragment tree's already
page-local rects (FragmentEmitter subtracts each band's top at build
time), but painted the actual text via CssBox.PaintWords, which reads
CssRect.Rectangle straight off the live box tree - still absolute
document-Y - offset only by ScrollOffset (always zero for PDF
generation). Confirmed via a raw PDF content-stream inspection: every
page after the first had zero text-draw (Tj) operators, since a fresh
per-page XGraphics's origin is that page's own band top, not the
document's. No existing test caught this because none checked page
content beyond page count. The same absolute-vs-fragment-local mixup
existed in this session's own image/frame content painters and in the
overflow-clip helper.

FragmentPainter now distinguishes the two coordinate spaces explicitly:
FragmentLocalOffset for geometry already sourced from the fragment tree,
LiveTreeOffset (and RenderUtils.ClipGraphicsByOverflow's new extraOffset
parameter) for geometry read straight off the live CssBox tree, which
additionally undoes the current fragmentainer's band top. Added a
regression test that asserts every page of a genuinely multi-page PDF
has real text operators, not just a page count.

With that fixed, HtmlContainerInt.PerformPaint(RGraphics)'s multi-
fragmentainer branch now paints every fragmentainer through
FragmentPainter (translated back to its real document-Y band top),
making CssBox.Paint/PaintImp and their three subclass overrides
genuinely unreachable - confirmed via grep and deleted, along with
CssBox's now-dead IsRectVisible helper.

Full regression suite (35 image-diff tests) and PDF suite (16 tests,
including the new one) pass; whole solution builds clean across all TFMs.

FragmentPainter painted backgrounds/borders/decoration from
fragment.Lines (already fragment-tree-local) but text via
CssBox.PaintWords, which iterated box.Words directly - live,
absolute-document-Y CssRect.Rectangle - reconciled with LiveTreeOffset's
band-top subtraction. BoxFragment.Words (TextFragment records) already
existed, already correctly band-localized by FragmentEmitter, and was
simply unused for the actual draw call.

Split CssBox.PaintWords into CssBox.PaintWord(g, word, wordRect): a
single-word primitive taking an already-final rect instead of computing
one from live geometry plus an offset parameter. FragmentPainter now
loops fragment.Words directly, offsetting each TextFragment.Rect by the
same FragmentLocalOffset Lines already uses - no band-top reconciliation
needed for text at all, since the geometry was never live to begin with.

First stage (R0) of the plan to replace HTML-Renderer's local-correction
fragmentation with a real resumable pass-loop matching PeachPDF's
architecture. Pure paint-side change, no layout code touched. Full
regression suite (35 pixel-diff tests, 16 PDF tests) passes with zero
pixel differences.

Replaces the local-correction handling of forced break-before/after:page
with a genuine multi-pass driver loop, the foundation stage of the plan
to match PeachPDF's resumable fragmentation architecture instead of this
port's single-pass-plus-OffsetTop-shift model.

HtmlContainerInt.PerformLayout gains DriveLayoutPasses: when the
container has a real page grid, it repeatedly calls CssBox.PerformLayout
on the root, resuming from wherever the previous pass left off
(root.PendingBreakToken), until nothing is left pending. For a document
with no forced breaks, or no real page grid (WinForms/WPF), this runs
exactly once - behaviorally identical to the old single call.

CssBox gains the actual resumption machinery: ResumeAt seeds a box's
incoming BreakToken/top-override for the pass about to run;
PendingBreakToken/RequestedBreakBeforeTop are how a break discovered
arbitrarily deep in the tree reaches the driver - every block-child loop
checks its own child's outcome immediately after the child's layout call
returns, wraps it in a BlockBreakToken naming itself, and stops laying
out further siblings this pass, so the signal bubbles up through
call-stack unwind alone, matching PeachPDF's actual mechanism. A box
whose forced break fires is not placed at all this pass (RectanglesReset/
MeasureWordsSize already ran, but no Location/content-layout work
happens) - deferred whole to the pass that resumes at it.

BlockFragmentation.ResolveBlockTop loses its forced-break branch (now
handled by CssBox itself, before ResolveBlockTop is even reached); the
decision logic moves to a new TryGetForcedBreakTarget, unchanged in
substance from the old inline computation. Margin truncation and
break-inside:avoid/monolithic relocation remain local single-pass
corrections for now - later plan stages (R2-R4) replace those too.

New tests exercise the loop across multiple passes specifically (two
forced breaks in sequence, and 50 in sequence terminating promptly),
which the existing single-break tests don't. Full regression suite (37
IntegrationTest + 16 PdfSharp tests, up from 35+16) passes unchanged -
every existing forced-break test now runs through the new pass loop
rather than the old inline computation, with identical output.

…lded in)

R2 ("overflow-driven block breaks") turned out to be a no-op given this
architecture: RelocateIfNeeded already does nothing for ordinary
(non-avoid, non-monolithic) content - it's left to split naturally via
the same recursive child-loop/InlineFragmentation math that already
produces correct positions, with no "does this fit" decision applicable
to a plain block container. There was no core case for R2 to convert.
Folding straight into R3, the first stage with a real behavior/code
change.

RelocateIfNeeded now relays the child out fresh at its target position
(CssBox.ResumeAt + a second PerformLayout call, within the same pass)
instead of OffsetTop-shifting its already-finished geometry. This is
strictly more correct, not just architecturally purer: a relaid-out
child's own descendants that have their own break-inside:avoid or a
nested forced break get to make that decision relative to the real page
boundaries at the NEW position, where a flat OffsetTop shift would have
carried whatever decision they made at the old one unchanged - possibly
wrong once the shift lands them against a different boundary. Keep-with-
next (the preceding-run shift) stays the older OffsetTop correction for
now; R4 converts that together with margin truncation.

Fixed a real ordering bug surfaced while touching this code: the child
loop called RelocateIfNeeded before checking whether the child's own
child loop had stopped mid-way (a nested forced break) - a child in
that state never reaches its own epilogue, so ActualBottom/Location only
reflect a partial pass, and RelocateIfNeeded's straddle test would have
read meaningless geometry. Reordered so a pending nested break is
checked and bubbled first; also re-checked after the relocation relayout
itself, since that relayout can surface its own nested break. Extracted
the repeated bubble-and-stop logic into CssBox.BubbleChildPendingToken.

New test: a scroll-container (overflow:hidden) taller than one page
confirms it's left straddling the boundary in place, not moved (nowhere
to move it to would help) or looped. Full regression suite (38
IntegrationTest + 16 PdfSharp tests) passes unchanged.

Found while implementing this stage: keep-with-next never actually
worked for the ordinary case. The old mechanism only ran as a side
effect of RelocateIfNeeded moving a child that was ITSELF break-inside:
avoid or monolithic - so it only ever fired when the box AFTER a
break-after:avoid heading also happened to be avoid/monolithic. The
common case (an unremarkable paragraph that simply doesn't fit after a
keep-with-next-chained heading) never triggered it: the heading was
left stranded alone at the bottom of its page while the paragraph moved
on by itself. Confirmed via a calibrated reproduction: heading provably
fit alone on page 0 in isolation, but adding the paragraph back left the
heading on page 0 anyway with the paragraph alone on page 1.

The existing KeepWithNext_HeadingStaysWithFollowingParagraph PDF test
didn't catch this because it only asserts a page COUNT of 2, which is
identical whether the pair moves together or splits - both outcomes
total 2 pages either way. New tests
(StageR4KeepWithNextTest) check the fragment tree directly for which
page actually holds the heading, and would have failed against the old
behavior.

BlockFragmentation.EnforceKeepWithNext is the fix: checked unconditionally
after a child finishes laying out (and after any R3 relocation), not
only as R3's side effect - if a page break actually falls between a
child and a preceding sibling chained to it by break-after/before:avoid,
the whole chained run is pulled down to the child's page and the child
is relaid out fresh. RelocateIfNeeded's own keep-with-next handling was
removed as redundant: after it moves a child, the preceding sibling is
exactly as stranded as in the ordinary case, and EnforceKeepWithNext
(called right after in the same loop iteration) now covers both
uniformly.

Also corrected course on two of the plan's own framing details, both
discovered only by implementing them: BlockFragmentation.cs is not
being retired (margin truncation is pre-placement arithmetic with
nowhere else to naturally live, same timing as the forced-break check);
the "R2" stage was folded into R3 last commit since it had no distinct
work of its own in this architecture.

Full regression suite (40 IntegrationTest + 16 PdfSharp tests) passes.

Investigated the plan's R5 (inline resumption via line-index
InlineBreakToken) and R6 (widows as a driver-level rewind) before
building either. Conclusion: CreateLineBoxes already computes a whole
paragraph's lines in one unbounded, side-effect-free, idempotent call -
there is never a point where a LATER pass would reveal information the
SAME-shot correction didn't already have, which is the entire reason
PeachPDF's resumption/rewind machinery exists. Building BreakToken/pass
machinery for inline flow would have been solving a problem this
architecture doesn't have (same conclusion as R2's finding for ordinary
block overflow).

What the investigation found instead: a real, confirmed bug in the
EXISTING same-shot algorithm. The old InlineFragmentation.ApplyLineBreaking
shifted lines incrementally as it walked them, driven by "did this line
straddle a page boundary". Once a shift happened to land a run in
perfect page-boundary alignment (common with uniform line heights), no
line ever straddled again for the rest of the paragraph - so widows was
silently never re-checked for any later page transition. Confirmed via
a paragraph spanning 60 pages: its final page ended with 1 line despite
widows:3, and nothing corrected it. Rewrote ApplyLineBreaking as two
phases: decide every break point from each line's own NATURAL
(never-shifted) position (immune to the alignment blind spot, and lets
widows cascade backward across more than one earlier break by removing
entries from a decided break list, rather than needing to undo a shift
already applied to specific lines), then apply the decided breaks as
shifts in one separate pass. Also handles a case the old code never
covered either: a box's own first line not fitting the room left on
its starting page.

Fixing this surfaced a second real bug in R4's own EnforceKeepWithNext:
it read CssBox.Location.Y to determine which page an already-laid-out
box's content starts on, but for an inline-only box, Location is
committed once before content layout runs and InlineFragmentation
never updates it - even though it can move the box's one-and-only line
to an entirely different page. A single-line heading whose own line
got pushed to the next page still reported its OLD page via Location.Y,
so keep-with-next silently compared against stale geometry. Added
CssBox.EffectiveTop (the first line's actual top for inline-only boxes,
Location.Y otherwise) and switched both RelocateIfNeeded and
EnforceKeepWithNext to use it.

New tests confirm both the fixable case (a long paragraph correctly
pulls lines back across more than one earlier page to satisfy widows
when room allows) and the honest unsatisfiable case (widows is left
unsatisfied rather than forcing an overflowing page, with word-count
conservation and per-page height checked directly). StageR4KeepWithNextTest
was also made self-calibrating (searches for the exact boundary filler
count rather than a hardcoded one) after the InlineFragmentation rewrite
shifted where that boundary falls by one - a hardcoded magic number
turned out to be fragile to unrelated, still-correct changes.

Full regression suite (41 IntegrationTest + 16 PdfSharp tests) passes.

…layout

Found while investigating the plan's R7 stage (table resumption), before
writing any new table code: CssLayoutEngineTable's row loop calls
cell.PerformLayout directly and does not participate in the
PendingBreakToken bubbling protocol an ordinary block-child loop does -
a table row is not itself laid out via that loop, so nothing ever reads
a cell's own PendingBreakToken and turns it into a real pass boundary.

Before R1, a forced break inside a table cell just computed an adjusted
top inline, in the same single continuous pass everything else used -
harmless. After R1, a forced break anywhere (including inside a table
cell) requests deferral to a later pass and returns from PerformLayoutImp
without calling CreateLineBoxes - but MeasureWordsSize already ran
unconditionally before that point, so the deferred content's words had
real sizes but stale/default (0,0) positions. Confirmed by direct
fragment-tree inspection: the content wasn't lost, it silently rendered
overlapping whatever else was in the cell, with no new page ever
created for it.

Fix: CssBox.CanDeferToLaterPass() walks a box's own ancestor chain for
a table-cell boundary; a forced break found there falls back to
immediate same-pass placement (the pre-R1 behavior) instead of
deferring, since deferring here could never actually be resumed. Not
full parity (this content doesn't get its own fresh fragmentainer pass
the way top-level content does), but correct rather than silently
corrupted - matching this port's established pattern of local
correction where true resumption isn't wired up yet.

R3 (avoid/monolithic relocation) and R4 (keep-with-next) are unaffected -
both relayout within the same pass rather than deferring across passes,
so they never depended on the block-child-loop bubbling chain reaching
past a table cell boundary in the first place.

New regression test constructs the exact scenario and verifies both
markers are present and correctly ordered by ABSOLUTE document-Y
(reconstructed from each fragmentainer's own band top, since raw
fragment-local Y values aren't comparable across different pages).
Full regression suite (42 IntegrationTest + 16 PdfSharp tests) passes.

…tion documented

Investigated before writing any new table-fragmentation code (same
approach as R2/R5/R6): table cells route their own content through the
same CssBox.PerformLayoutImp/CreateLineBoxes/ApplyLineBreaking machinery
as any other box, so a cell's own paragraphs already correctly benefit
from every R1-R6 fix for free. Confirmed via direct testing: a table
cell whose own content spans several pages by itself preserves all
content correctly, and subsequent rows correctly continue after it -
no TableBreakToken/TableRowCursor machinery needed for this, matching
the R2/R5/R6 pattern of this architecture rarely needing what it looks
like it needs at first glance.

The same investigation found one real, confirmed remaining gap:
CssLayoutEngineTable.LayoutCells's repeated-<thead> check runs once per
ROW (checking the layout cursor's page slot only at that row's own
start) - so a row whose own cell content spans MULTIPLE pages by itself
only gets a header repeat inserted for the first page it crosses onto,
not further intermediate pages that same row continues to span. Not
data loss or a crash, just a missing header repeat on some pages of a
fairly exotic table shape (one cell vastly longer than its siblings, in
a table with a repeating header). A real fix needs to know how many
pages a row spans before deciding how much room to reserve for it,
which requires relaying the row out a second time once its true span is
known - tractable, but deliberately left as a documented, out-of-scope
limitation given how rare the shape is versus the far more common case
(many ordinary rows, table spans many pages), which already repeats
correctly per the existing ThreadRepeatsOnEveryPageTheTableSpans test.

New test confirms the working case (no data loss for a multi-page-
spanning cell); the known-limitation comment lives directly beside the
code it describes rather than a test asserting broken behavior as
correct. Full regression suite (43 IntegrationTest + 16 PdfSharp tests)
passes.

…nd needed

Investigated the plan's highest-risk stage before implementing PassRewind/
depth-limited-lookback machinery. Only forced breaks create genuine cross-pass
boundaries in DriveLayoutPasses (overflow and break-inside:avoid are same-pass
local corrections per R2/R3), and FragmentEmitter runs once at the very end -
so nothing is ever truly "frozen" mid-layout the way PeachPDF's per-pass
EmitPass makes it. Confirmed empirically: a keep-with-next pair placed
immediately after resuming from an unrelated forced break still lands
together, handled by the existing same-pass EnforceKeepWithNext (R4).
Same finding pattern as R2/R5/R6: the machinery this stage describes solves a
problem specific to PeachPDF's real multi-pass-for-everything architecture,
which this port's local-correction design doesn't have.

…one page

EnforceKeepWithNext previously pulled the WHOLE preceding break-after:avoid
chain to a child's page unconditionally, without checking whether the run fit
there. For a long chain taller than one page, each subsequent chained
sibling's own keep-with-next check re-fired against the now-stretched-out
run, compounding OffsetTop shifts on the same earlier boxes without bound -
found via a targeted stress test (60-member chain), reaching a box position
around 8.6e11 and producing zero fragmentainers (FragmentEmitter couldn't
bucket geometry that far out of range).

Implements css-break-3 section 4.3's actual staged relaxation: trim the run
from its front until what remains fits alongside the child on the target
page, or leave the run in place entirely (RunDropped) if even its last member
doesn't fit. Matches the BreakRelaxation enum's documented but previously
unused RunTrimmed/RunDropped cases.

InlineBreakToken, its FanOutContinuations base member, and the
BreakRelaxation enum were ported early on for machinery this port's
architecture turned out not to need (R2/R5/R6/R9 all found the local-
correction model handles their cases without real cross-pass tokens - see
each stage's commit). None had a single caller anywhere in the codebase.
BlockBreakToken is the only token kind this port actually uses; the doc
comments now say so directly instead of pointing at unused alternatives.

InlineFragmentation.ApplyLineBreaking's orphans merge-back correction only
ever ran once at least one earlier break already existed (breaks.Count > 1),
which can never be true while still deciding the first run - so a paragraph
starting close enough to a page's bottom that fewer than `orphans` lines fit
there was left with a too-small stranded first fragment. Confirmed by
temporarily reverting the fix: it reliably reproduced a 1-line first page
against orphans:2 at several filler counts.

Generalizes the existing "first line taller than the remaining room" push
(now folded into the same check, since 0 fitting lines is just the orphans
violation that can never be waived) - if fewer than `orphans` lines fit in
the room remaining on the starting page, the whole paragraph now moves to
start fresh on the next page instead.

…row-shift

CssLayoutEngineTable.LayoutCells's row-shift correction did
`foreach (cell in row.Boxes) cell.OffsetTop(delta)` - but for a row that is
the END of a rowspan, row.Boxes holds only the CssSpacingBox placeholder
(Display:none, no children/words/rectangles), not the real spanning cell
(ExtendedBox). OffsetTop on the placeholder was a silent no-op, leaving the
spanning cell's real bottom edge stale while the rest of the row moved to
the next page. Confirmed by temporarily reverting the fix: it reliably
reproduced the spanning cell's bottom lagging behind its sibling's.

Fix extends the spanning cell's ActualBottom (bottom edge only) rather than
OffsetTop-ing its whole subtree: its top and content are already anchored to
whichever earlier row it started in and shouldn't move, only its bottom edge
needs to extend to cover the gap the row-shift just opened up.

css-break-3 3.1's break-point propagation was only ever applied to forced
breaks (TryGetForcedBreakTarget's own "no previous sibling" check), never to
RelocateIfNeeded's relocation, EnforceKeepWithNext's run-pull, or
InlineFragmentation's own orphans-driven whole-box push. A box moved by any
of these while it's its parent's first in-flow child left the parent
spanning from its original page to the moved content's new one - its own
background/border rendered as a stub-then-continuation (e.g. a card/panel
div wrapping a single table, or a section wrapping a heading+paragraph
pair). Confirmed via three separate reproductions, each failing without the
fix and passing with it.

New BlockFragmentation.PropagateContainerRelocation(movedBox, delta): climbs
the first-in-flow-child chain, shifting each such ancestor's own top by the
same delta. Deliberately touches only Location, never ActualBottom - a
container's bottom is already correctly, independently computed from its
last child via ordinary block flow, so no "does the whole group move
together" bookkeeping is needed, unlike an earlier, more complex version of
this fix that tried (and got wrong) recomputing both edges from a moved
group's combined extent.

Investigating the EnforceKeepWithNext case surfaced a second, more
fundamental bug along the way: CssBox.OffsetTop kept the box's own
Rectangles dictionary in sync with a shift but never the corresponding
CssLineBox.Rectangles entry (a separate dictionary, keyed the other way,
that LineTop/LineBottom - and therefore EffectiveTop for any inline-only
box - read from). Location.Y was correctly updated while EffectiveTop
silently kept reporting the pre-shift position. Fixed by having OffsetTop
update both sides together, matching what CssLineBox.ShiftLine already does
when a line-level shift initiates the move instead.

A third audit pass raised a plausible concern: does PropagateContainerRelocation's
raw Location reassignment leave a list-item's marker stale, the way it would
without CssBox.OffsetTop's explicit marker handling? Investigated empirically
with a diagnostic test (with and without an explicit marker shift) - no
difference. CreateListItemBox recomputes the marker's position from its
owner's current Location unconditionally on every PerformLayoutImp call, and
every ancestor this method climbs is still mid-PerformLayoutImp when it
runs, so the marker always re-derives correctly afterward. Recorded as an
investigated non-issue rather than adding redundant handling.

Verified directly against the current W3C Editor's Draft
(drafts.csswg.org/css-tables-3/#breaking-rules): "user agents must attempt
to preserve the table rows unfragmented if the cells spanning the row do not
span any subsequent row, and their height is at least twice smaller than
both the fragmentainer height and width" - a required UA default, not
something an author opts into. The table's row-shift previously only fired
when the table itself had explicit break-inside:avoid, meaning an ordinary
multi-page table with no special markup rendered rows split across page
boundaries by default - not spec-compliant.

CssLayoutEngineTable.LayoutCells now attempts to preserve every row by
default, with the spec's two carve-outs implemented as "freely fragmentable"
exceptions: a row a cell only starts spanning into a later row (new
RowHasCellSpanningIntoSubsequentRow helper), or a row taller than half the
page's height or width. The table's own break-inside:avoid still forces the
attempt even for an otherwise-freely-fragmentable row, preserving existing
behavior for that explicit case.

Verified against the actual W3C spec text (css-position-3): "in paged
media, the page area of each page; fixed positioned boxes are thus
replicated on every page", and UAs "must not paginate the content of
fixed-positioned boxes". Scoped to top/left-anchored fixed content only
(a page header/watermark) - bottom/right are a separate, pre-existing gap:
neither property is parsed for absolute/fixed positioning at all, so a
bottom-anchored footer, the more common real print pattern, needs that
fixed first.

FragmentEmitter now collects every position:fixed box in the tree
(CollectFixedRoots, handling arbitrary nesting depth) and, for each
materialized page, builds a fresh fragment for it against a page-local band
(top=0) rather than the page's real band top - a fixed box's own Location is
already page-relative (CssBox.PerformLayoutImp's Position==Fixed branch
never routes it through normal absolute-Y-computing flow at all), so this
reuses the same geometry unchanged on every page. Excluded from the normal
per-page walk to avoid a duplicate/misplaced render on whichever page its
raw offset would otherwise land on. InlineFragmentation.ApplyLineBreaking
now also skips fixed boxes outright - their content must not paginate.

Confirming this through actual PDF output (not just the fragment tree)
surfaced a second, real, pre-existing bug: FragmentPainter.LiveTreeOffset/
LiveTreeExtraOffset unconditionally undid the current page's band top from
live-tree geometry, on the documented assumption that "band membership is
orthogonal to scroll-offset suppression" for fixed content. That assumption
was true when fixed content only ever appeared on one page (wherever its
raw offset landed) but breaks now that it's intentionally repeated: a fixed
box's live geometry is already page-relative, so subtracting a nonzero band
top pushes its containing-block visibility/overflow-clip check far outside
every page except the one whose band top happens to equal its own small
offset - confirmed via a real generated PDF, where the header only rendered
on page 0. Fixed by making both offsets skip the band-top term entirely for
fixed (or fixed-ancestor) content.